Inside Macintosh: 3D Graphics Programming With QuickDraw 3D /

Chapter 3 - QuickDraw 3D Objects / QuickDraw 3D Objects Reference

QuickDraw 3D Objects Routines / Registering Custom Elements

Q3ElementClass_Register

You can use the Q3ElementClass_Register function to register an application-defined element class.

TQ3ObjectClass Q3ElementClass_Register (
TQ3ElementType elementType, 
char *name, 
unsigned long sizeOfElement, 
TQ3MetaHandler metaHandler);

elementType

An element type.

name

A pointer to a null-terminated string containing the name of the element's creator and the name of the type of element being registered.

sizeOfElement

The size of the data associated with the specified custom element type.

metaHandler

A pointer to an application-defined metahandler that QuickDraw 3D calls to handle the new custom element type.

DESCRIPTION

The Q3ElementClass_Register function returns, as its function result, an object class reference for a new custom element type having a type specified by the elementType parameter and a name specified by the name parameter. The metaHandler parameter is a pointer to the metahandler for your custom element type. See "Defining an Object Metahandler," beginning on page 3-15 for information on writing a metahandler. If Q3ElementClass_Register cannot create a new element type, it returns the value NULL.

The name parameter should be a pointer to null-terminated C string that contains your (or your company's) name and the name of the type of element you are defining. Use the colon character (:) to delimit fields within this string. The string should not contain any spaces or punctuation other than the colon character, and it cannot end with a colon. Here are some examples of valid creator names:

"MyCompany:SurfDraw:Wavelength"
"MyCompany:SurfWorks:VRModule:WaterTemperature"

The sizeOfElement parameter specifies the fixed size of the data associated with your custom element type. If you wish to associate dynamically sized data with your element type, put a pointer to a dynamically sized block of data into the set and have your handler's copy method duplicate the data. (In this case, you would set the sizeOfElement parameter to sizeof(Ptr).) You also need to have your handler's dispose method deallocate any dynamically sized blocks.

SEE ALSO

See page 3-29 for information on writing copy and dispose methods for a custom element type.